Games of Daze/Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso/djgpp/tktdoc/porting.doc

Text File | 1994-08-11 | 9.3 KB | 209 lines

PORTING APPLICATIONS FROM UNIX TO DESQVIEW/X

This chapter gives guidelines and helpful hints for porting UNIX X  Window
clients from UNIX to the DESQview/X DOS environment. It provides an
overview of porting issues, the preparation of files for the DOS environment
and traps related to the porting process.

The basic porting strategy is to:

- copy the source files to your DOS machine and resolve
  file naming conflicts,
- substitute header file #includes,
- write a makefile for your program,
- work around or remove unix specific code,
- resolve compiler differences,
- make your program and
- run and debug your program.

The strategy is straight forward and it can sometimes be extremely
easy to port programs from UNIX to DESQview/X.

Copy Source Files

You can use FTP or the DESQview/X File Manager to transfer files from
other machines across the network.

Part of the process of getting the files onto your machine is to resolve
file names to DOS eight character names with three character extensions
(i.e., NNNNNNNN.EEE). If you were to just get all of the files without
resolving the names first, your files that have more than eight character
names will get truncated to eight character names. This might work
out to be okay as long as they got truncated uniquely to an eight
character names. This is often not the case and you will need to resolve
the conflict by renaming the applicable files on the UNIX machine
prior to your copying them over.

It can sometimes be convenient to do all of the filename resolution
on the other end and then zip the files and just copy over one zip
file, then unzip it on your DOS machine. When using FTP or fileman
to copy a zipped file make sure to copy the files in binary mode.
If you do not, the zip file will be corrupt. During this process,
keep a list of all of the header files names that you changed. It
will be used in the next step.

Substitute Header File #include Names

Once you have your source files copied over uniquely you will need
to resolve the #include header file names within your source. This
process is made easier by the use of the utility UNIX2DVX.EXE.

Put all of your source and header files in the current directory.
Copy the UNIX2DVX.TXT file into your current directory. This file
contains header file name substitutions for X and Motif. Edit your
private copy to include your own header file name substitutions.

Do C:MYPORT> UNIX2DVX *.C PORTC.LIS

This will make the header file name substitutions within an #ifdef
MSDOS construct. This way the substitution will only be made if MSDOS
is defined. Review the PORTC.LIS file for substitutions that were
not made because they were already within an #ifdef construct.   You
will have to make these substitutions manually using an editor.

See the WRAPPER.TXT file. UNIX2DVX.EXE uses it to get the substitution
format. You may customize it for yourself if you wish.

Repeat this process for the header files (i.e., C:\MYPORT> UNIX2DVX
*.H PORTH.LIS).

Write a Makefile For Your Program

Identify what sources get linked into your program and write a makefile.
It is sometimes easy to clone an existing makefile out of the DEMOS
or CLIENTS directory.

Copy one that uses the model that you want (ie. HCLE, WC4G or MAKEFILE).

Work Around or Remove UNIX Specific Code

When making any changes to source, it is best to #ifdef MSDOS the
changes. This way the things that you did to accomplish the port are
documented and the source will still compile on its original platform.

Work around or remove UNIX specific code. Notable functions that are
missing from DOS compilers are signal(), fork(), exec() and pipes.

The DESQview/X system library routine that is used to start another
process is pif_start(). See Chapter 9: The DESQview/X System
Library.

Change '/'s in file path names to '\\' since DOS uses '\' as the path
delimiter. The reason that you need two backslashes is because the
first backslash is used as the literal character. Many DOS compiler
functions will accept forward slashes as directory delimiters. The
fopen() function is one of these. Check it with your particular compiler.

Some UNIX programs refer to files in /usr/... . There is not a /usr
directory in the default DESQview/X installation.

Some UNIX programs look for the /TMP directory, it is not there by
default. It can be helpful to define a TEMP environment variable to
point to where your temp directory is and get it with a getenv() at
runtime.

Bitmaps are kept in \DVX\INCLUDE\X11\BITMAPS instead of
/USR/X11/INCLUDE/BITMAPS.

In UNIX you can read() and write() to a Berkeley socket. This does
not work under DOS. Change your read()s to recv()s and your write()s
to send()s. A trick that you can use in the routine that does the
read() and write() is to make a #define macro that replaces write(args)
with send(args) and read(args) with recv(args). Just be careful only
to define it for the routines that use it in this way.

If you are reading a binary file that was generated on another platform,
you have to be cognizant of what the byte ordering and structure alignment
were on that platform and accommodate accordingly.

For instance, on a Sparc platform the byte ordering is MSB or big-endian
and on the PC the byte ordering is LSB or little-endian. If you were
reading a binary file generated on the Sparc that had IEEE 32-bit
floating point numbers or 32 bit integers then you would need to byte
swap the data before your application used it. For 32 bit numbers,
you would swap byte 1 with byte 4 and byte 2 with byte 3.

If you are reading a binary file that was generated by writing out
structures, you have to be aware of what the structure alignment and
padding policy was for the compiler that was used to compile the program
that generated the binary file. You cannot necessarily just use the
same structure definition on another platform and just read the binary
data into the structure.

Resolve Compiler Differences

DOS compilers are often times more particular than are the UNIX cc
compilers. Often code that compiles code fine with cc will not compile
with DOS compilers. Some common things that cause code not to immediately
compile are duplicate defined functions, structures or #defines, function
arguments that do not match the function prototype or the use of common
macro defines that happen not to be defined for your compiler environment.

Your code may generate many compiler warnings, such as the ones that
you may see in the demos and clients that came with the toolkit. Many
of the warnings are harmless and you can ignore them. However, for
a real world deliverable application, it would be most prudent to
examine each of the warnings carefully and eliminate them if possible.

It is always good to prototype your own functions. It does not take
much time to do it and it can sometimes point out a nasty bug immediately
which otherwise would have been difficult to find.

Build Your Program

If everything was done 100 percent correctly and you planned for every
contingency then your program should compile and link the first time.  It
does happen that way sometimes.

Build your program by doing

C:\MYPORT> qmake -x -f "makefile name"

You may find some errors in your makefile or some unresolved externals
at link time. You will need to deal with the unresolved externals
on a case by case basis.

Once you get your program to link then you can go on to running and
debugging it.

Running and Debugging Your Program

Before running your program make sure that your environment is set
up properly for your program. Sometimes programs use environment variables
at runtime by calling getenv(). Make sure that any data files that
the program uses are available and in the right places.

If your program crashes upon startup, check the trouble shooting section
in Appendix A for tips. Sometimes something simple like not
having a large enough stack can cause a crash.

Once obvious things have been eliminated,  make a debug version of
your program, see where it crashes and take it from there. Some useful
tools or tricks in helping you debug your program are:

XSync() can be called to force synchronous execution,
ensuring that all events are processed as they occur. This is particularly
useful at the toolkit level. Also see XSynchronize() and XFlush in
the Xlib reference manual.

Display your program remotely on another server,  maybe
the one on the platform from which you ported it. This could help
identify a server problem. Applications should be tested on as many
different servers as possible. Anomalies that occur on one server
may disappear on another, meaning that a server inconsistency has
caused the problem.

For obscure bugs, running without a window manager
can serve to further isolate the problem.

Private error handlers can be written to trap particular
errors. The private error handler can print out a diagnostic and continue
program execution.

Some  problems in porting X Clients arise from the nature of the X
Window System itself, especially if it is new to you. Event driven
programming, the network model, layers of libraries and their interdependency,
all contribute to the complexity with which you must deal. Working
through a successful port will go far in providing the expertise needed
for new development.